From f81e6042be9e15a3f14b02e9ffc8f1cbafd995d8 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 30 Apr 2020 14:05:23 +0100 Subject: [PATCH] docs: Remove use of gtk_dialog_run() Direct people to use GTK_DIALOG_MODAL and the "response" signal instead of nested main loops. --- gtk/gtkaboutdialog.c | 5 +- gtk/gtkfilechooserdialog.c | 125 ++++++++++++++++++++++--------------- gtk/gtkmessagedialog.c | 30 +++++---- 3 files changed, 95 insertions(+), 65 deletions(-) diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c index 6b18fe8413..96411e26a8 100644 --- a/gtk/gtkaboutdialog.c +++ b/gtk/gtkaboutdialog.c @@ -104,8 +104,9 @@ * ]| * * It is also possible to show a #GtkAboutDialog like any other #GtkDialog, - * e.g. using gtk_dialog_run(). In this case, you might need to know that - * the “Close” button returns the #GTK_RESPONSE_CANCEL response id. + * and use the #GtkDialog::response signal to catch user responses. In this + * case, you might need to know that the “Close” button returns the + * %GTK_RESPONSE_CANCEL response id. */ typedef struct diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c index 8449c321a6..46ce76e4d7 100644 --- a/gtk/gtkfilechooserdialog.c +++ b/gtk/gtkfilechooserdialog.c @@ -70,61 +70,86 @@ * #GtkFileChooserDialog to select a file for opening: * * |[ - * GtkWidget *dialog; - * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; - * gint res; - * - * dialog = gtk_file_chooser_dialog_new ("Open File", - * parent_window, - * action, - * _("_Cancel"), - * GTK_RESPONSE_CANCEL, - * _("_Open"), - * GTK_RESPONSE_ACCEPT, - * NULL); - * - * res = gtk_dialog_run (GTK_DIALOG (dialog)); - * if (res == GTK_RESPONSE_ACCEPT) - * { - * GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); - * g_autoptr(GFile) filen = gtk_file_chooser_get_file (chooser); - * open_file (file); - * } - * - * gtk_window_destroy (dialog); + * static void + * on_open_response (GtkDialog *dialog, + * int response) + * { + * if (response == GTK_RESPONSE_ACCEPT) + * { + * GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); + * + * g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); + * + * open_file (file); + * } + * + * gtk_window_destroy (GTK_WINDOW (dialog)); + * } + * + * // ... + * GtkWidget *dialog; + * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_OPEN; + * + * dialog = gtk_file_chooser_dialog_new ("Open File", + * parent_window, + * action, + * _("_Cancel"), + * GTK_RESPONSE_CANCEL, + * _("_Open"), + * GTK_RESPONSE_ACCEPT, + * NULL); + * + * gtk_widget_show (dialog); + * + * g_signal_connect (dialog, "response", + * G_CALLBACK (on_open_response), + * NULL); * ]| * * To use a dialog for saving, you can use this: * * |[ - * GtkWidget *dialog; - * GtkFileChooser *chooser; - * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; - * gint res; - * - * dialog = gtk_file_chooser_dialog_new ("Save File", - * parent_window, - * action, - * _("_Cancel"), - * GTK_RESPONSE_CANCEL, - * _("_Save"), - * GTK_RESPONSE_ACCEPT, - * NULL); - * chooser = GTK_FILE_CHOOSER (dialog); - * - * if (user_edited_a_new_document) - * gtk_file_chooser_set_current_name (chooser, _("Untitled document")); - * else - * gtk_file_chooser_set_file (chooser, existing_filename); - * - * res = gtk_dialog_run (GTK_DIALOG (dialog)); - * if (res == GTK_RESPONSE_ACCEPT) - * { - * g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); - * save_to_file (file); - * } - * - * gtk_window_destroy (dialog); + * static void + * on_save_response (GtkDialog *dialog, + * int response) + * { + * if (response == GTK_RESPONSE_ACCEPT) + * { + * GtkFileChooser *chooser = GTK_FILE_CHOOSER (dialog); + * + * g_autoptr(GFile) file = gtk_file_chooser_get_file (chooser); + * + * save_to_file (file); + * } + * + * gtk_window_destroy (GTK_WINDOW (dialog)); + * } + * + * // ... + * GtkWidget *dialog; + * GtkFileChooser *chooser; + * GtkFileChooserAction action = GTK_FILE_CHOOSER_ACTION_SAVE; + * + * dialog = gtk_file_chooser_dialog_new ("Save File", + * parent_window, + * action, + * _("_Cancel"), + * GTK_RESPONSE_CANCEL, + * _("_Save"), + * GTK_RESPONSE_ACCEPT, + * NULL); + * chooser = GTK_FILE_CHOOSER (dialog); + * + * if (user_edited_a_new_document) + * gtk_file_chooser_set_current_name (chooser, _("Untitled document")); + * else + * gtk_file_chooser_set_file (chooser, existing_filename); + * + * gtk_widget_show (dialog); + * + * g_signal_connect (dialog, "response", + * G_CALLBACK (on_save_response), + * NULL); * ]| * * ## Setting up a file chooser dialog ## {#gtkfilechooserdialog-setting-up} diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c index be0b4afe2c..0d8636a016 100644 --- a/gtk/gtkmessagedialog.c +++ b/gtk/gtkmessagedialog.c @@ -49,14 +49,15 @@ * convenience widget; you could construct the equivalent of #GtkMessageDialog * from #GtkDialog without too much effort, but #GtkMessageDialog saves typing. * - * The easiest way to do a modal message dialog is to use gtk_dialog_run(), though - * you can also pass in the %GTK_DIALOG_MODAL flag, gtk_dialog_run() automatically - * makes the dialog modal and waits for the user to respond to it. gtk_dialog_run() - * returns when any dialog button is clicked. + * The easiest way to do a modal message dialog is to use the %GTK_DIALOG_MODAL + * flag, which will call gtk_window_set_modal() internally. The dialog will + * prevent interaction with the parent window until it's hidden or destroyed. + * You can use the #GtkDialog::response signal to know when the user dismissed + * the dialog. * * An example for using a modal dialog: * |[ - * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; + * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT | GTK_DIALOG_MODAL; * dialog = gtk_message_dialog_new (parent_window, * flags, * GTK_MESSAGE_ERROR, @@ -64,13 +65,17 @@ * "Error reading “%s”: %s", * filename, * g_strerror (errno)); - * gtk_dialog_run (GTK_DIALOG (dialog)); - * gtk_window_destroy (GTK_WINDOW (dialog)); + * // Destroy the dialog when the user responds to it + * // (e.g. clicks a button) + * + * g_signal_connect (dialog, "response", + * G_CALLBACK (gtk_window_destroy), + * NULL); * ]| * - * You might do a non-modal #GtkMessageDialog as follows: + * You might do a non-modal #GtkMessageDialog simply by omitting the + * %GTK_DIALOG_MODAL flag: * - * An example for a non-modal dialog: * |[ * GtkDialogFlags flags = GTK_DIALOG_DESTROY_WITH_PARENT; * dialog = gtk_message_dialog_new (parent_window, @@ -83,10 +88,9 @@ * * // Destroy the dialog when the user responds to it * // (e.g. clicks a button) - * - * g_signal_connect_swapped (dialog, "response", - * G_CALLBACK (gtk_window_destroy), - * dialog); + * g_signal_connect (dialog, "response", + * G_CALLBACK (gtk_window_destroy), + * NULL); * ]| * * # GtkMessageDialog as GtkBuildable -- 2.30.2